系统版本:1.2.1 (20240105)
文档创建日期:2023/11/28
文档最后更新:2024/01/05
此步骤Linux和Windows通用;
安装配置Mysql 5.7或更新版本(安装配置过程不在此详述);
配置Mysql参数,解决同步大数据接口时报错的问题:
1[mysqld]2max_allowed_packet = 100M
初始化数据,客户端工具连接Mysql:
在Mysql系统中,创建数据库:
| 属性 | 值 |
|---|---|
| Database Name | magic |
| Character set | utf8mb4 |
| Collation | utf8mb4_general_ci |
打开magic数据库,在查询窗口中执行initMagicApi.sql脚本,初始化数据;
安装配置Redis 6.2.x或更新版本(安装配置过程不在此详述);
安装配置JDK 1.8.0_291或更新版本(安装配置过程不在此详述);
启用256位以上的密码策略强度:
xxxxxxxxxx21cd $JRE_TOP/lib/security2vi java.security
将#crypto.policy=unlimited前面的 # 号去掉,变成:
xxxxxxxxxx11crypto.policy=unlimited
部署Magic-API管理系统,本次部署以路径/usr/local/为例说明,实际部署时根据项目情况修改;
创建目录:
xxxxxxxxxx101cd /usr/local2mkdir magic-api3mkdir -p magic-api/data4mkdir -p magic-api/images5mkdir -p magic-api/logs/info6mkdir -p magic-api/logs/debug7mkdir -p magic-api/logs/warn8mkdir -p magic-api/logs/error9mkdir -p magic-api/logs/plumelog10mkdir -p magic-api/uploadpath
上传下列文件至/usr/local/magic-api目录下:
| 序号 | 文件名 | 类型 | 说明 |
|---|---|---|---|
| 1 | madmin.sh | shell脚本 | 启动/停止Magic-API的Linux脚本 |
| 2 | application.yml application-prod.yml application-shiro.yml application-static.yml logback-spring.xml magic-editor-config.js | 配置文件 | 程序运行的配置项信息 |
| 3 | license.lic publicCerts.keystore | 许可证书 | 授权管理的许可证书文件 |
| 4 | magic-api.jar | jar文件 | 程序文件 |
| 5 | initMagicApi.sql | sql文件 | 初始化系统的sql语句 |
| 6 | images目录下的 loginbackground.jpeg loginlogo.png background.jpeg | 图片 | 可根据需要替换图片 loginbackground.jpeg:系统登录首页背景图片 loginlogo.png:系统登录首页logo图片 background.jpeg:系统主界面首页背景图片 |
修改配置信息
配置文件信息请参见“系统配置文件”部分说明;
修改文件可执行权限:
xxxxxxxxxx31cd /usr/local/magic-api2chmod +x magic-api.jar3chmod +x madmin.sh
启动系统:
启动Magic-API管理系统:
xxxxxxxxxx21cd /usr/local/magic-api2./madmin.sh start
停止Magic-API管理系统:
xxxxxxxxxx21cd /usr/local/magic-api2./madmin.sh stop
部署Magic-API管理系统,本次部署以路径c:\software\为例说明,实际部署时根据项目情况修改;
创建目录:
xxxxxxxxxx101cd c:\software\2mkdir magic-api3mkdir magic-api\data4mkdir magic-api\images5mkdir magic-api\logs\info6mkdir magic-api\logs\debug7mkdir magic-api\logs\warn8mkdir magic-api\logs\error9mkdir magic-api\logs\plumelog10mkdir magic-api\uploadpath
上传下列文件至c:\software\magic-api\目录下:
| 序号 | 文件名 | 类型 | 说明 |
|---|---|---|---|
| 1 | admagicstart.bat | bat脚本 | 启动/停止Magic-API的Windows脚本 |
| 2 | application.yml application-prod.yml application-shiro.yml application-static.yml logback-spring.xml magic-editor-config.js | 配置文件 | 程序运行的配置项信息 |
| 3 | license.lic publicCerts.keystore | 许可证书 | 授权管理的许可证书文件 |
| 4 | magic-api.jar | jar文件 | 程序文件 |
| 5 | initMagicApi.sql | sql文件 | 初始化系统的sql语句 |
| 6 | images目录下的 loginbackground.jpeg loginlogo.png background.jpeg | 图片文件 | 可根据需要替换图片 loginbackground.jpeg:系统登录首页背景图片 loginlogo.png:系统登录首页logo图片 background.jpeg:系统主界面首页背景图片 |
修改配置信息
配置文件信息请参见“三、系统配置文件”部分说明;
修改文件可执行权限:
确保执行命令的用户对magic-api.jar有读取和执行的权限。
启动系统:
启动Magic-API管理系统:
xxxxxxxxxx21cd c:\software\magic-api2admagicstart.bat
停止Magic-API管理系统:
关闭命令行窗口即可;
在浏览器中输入地址访问系统(根据实际IP地址和端口修改):
用户名: admin密 码:admin123
请使用Chrome/Firefox/Edge浏览器访问,部分功能页面不支持IE系列;
为保证正常访问系统,请在服务器端放行防火墙对端口的访问权限;
如果Redis服务器和Magic-API服务器不在同一台机器上,请在服务器端放行防火墙对Redis服务器端口的访问权限;
对于Linux系统,修改madmin.sh,用记事本编辑脚本文件,将其中的JAVA_TOP路径修改为实际jre/jdk安装的路径:
x1#!/bin/bash23# 取得当前Shell脚本所在绝对路径4MAGIC_API=$(cd "$(dirname "$0")";pwd)5JAVA_TOP=$MAGIC_API/jdk1.8.0_2916......
对于Windows系统,修改admagicstart.bat,用记事本编辑脚本文件,将其中的JAVA_TOP路径修改为实际jre/jdk安装的路径:
xxxxxxxxxx131@echo off2:设置窗口字体颜色3color 0a4mode con cols=60 lines=125:设置窗口标题6TITLE magic-api管理程序(windows版)78set MAGIC_FILE=magic-api.jar9set MAGIC_LOG=magic-api.log10set JAVA_TOP=C:\Program Files\Java\jdk1.8.0_14411set JAR_PARAS=-Dfile.encoding=utf-8 -Djava.net.preferIPv4Stack=true12set MAGIC_TOP=%~dp013......
建议只修改application-prod.yml文件,其它yml文件保持默认配置;
配置测试环境时,可将application-prod.yml命名为application-dev.yml,同时修改application.yml中active: prod为active: dev即可;
注意Linux系统路径使用/正斜杠,Windows系统路径使用\反斜杠;
项目相关配置
xxxxxxxxxx81# 项目相关配置2cfg-project:3name: Magic-API管理系统 # 程序名称,可根据项目需要修改4version: 4.7.7 # 系统框架版本,默认即可5copyrightYear: 2023 # 版权年份6# 文件路径(用于上传用户头像,Windows配置D:/magic/uploadPath,Linux配置 /home/magic/uploadPath)7# 需要修改为项目实际路径8profile: /usr/local/magic-api/uploadpath
环境配置
xxxxxxxxxx31# 环境配置2cfg-server:3port: 8888 # 应用程序运行的HTTP端口(默认为80)
Magic-API配置信息
xxxxxxxxxx131# Magic-API配置信息2cfg-magic-api:3backup-max-history: 180 # Magic-API备份保留天数,-1为永久保留4# 前端界面引用的js文件,需要修改为项目实际路径5editor-config: /usr/local/magic-api/magic-editor-config.js6# Magic接口放行地址,不受ruoyi框架控制7exclude-path-patterns: /root/**,/erp/**,/test/**8# Magic禁止通过import env查看的配置信息9excludeEnvKey: '*.password,*.storePwd,*.secret-key'10# 实例ID,集群环境下,要保证每台机器不同。默认启动后随机生成uuid,如无特殊情况可不配置。11instanceId: 20927d75-7fa0-237d-80ed-c3b5b6f1a49812# 远程推送时的秘钥,未配置则不开启推送13secret-key:
数据源配置
xxxxxxxxxx61# 数据源配置,需要修改为数据库的实际配置信息2cfg-datasource:3driverClassName: com.mysql.cj.jdbc.Driver4url: jdbc:mysql://127.0.0.1:3306/magic?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B85username: root6password: root
Redis配置
xxxxxxxxxx61# 配置redis数据源2cfg-redis:3database: 04host: 127.0.0.15port: 63796password: test123
登录配置
xxxxxxxxxx51# 登录配置2cfg-login:3captchaEnabled: true # 登录界面是否启用验证码4expireTime: 60 # Session超时时间,-1代表永不过期(默认30分钟)5maxRetryCount: 5 # 密码错误连续超过{maxRetryCount}次锁定10分钟
Swagger配置
xxxxxxxxxx31# Swagger配置,注意正式环境需要关闭,设置为false;测试环境可打开,设置为true;2cfg-swagger:3enabled: false # 是否开启swagger
logging配置
xxxxxxxxxx51# logging配置2cfg-log:3# config配置文件,需要修改为项目的实际路径4configfile: /usr/local/magic-api/logback-spring.xml5path: /usr/local/magic-api/logs
Jasypt加密配置
xxxxxxxxxx31# jasypt加密,如果不清楚含义,可保持默认2cfg-jasypt:3password: 02700083-9fd9-4b82-a4b4-9177e0560e92
License证书管理配置
xxxxxxxxxx71# license证书管理,需要修改证书主题subject,以及证书路径为项目实际路径2cfg-license:3subject: MagicAPI管理系统4public-pwd: magic6665storePwd: magic6666public-keys-store-path: /usr/local/magic-api/publicCerts.keystore7license-path: /usr/local/magic-api/license.lic
magic-editor-config.js,前端运行需要配置信息,一般修改baseURL、serverURL、title三个信息即可;
xxxxxxxxxx121var MAGIC_EDITOR_CONFIG = {2baseURL: 'http://localhost:8888/magic/web', //需要修改为实际的端口3serverURL: 'http://localhost:8888/', // 需要修改为实际的端口4title: 'Magic-API管理', // 可根据需要修改为项目的名称5checkUpdate: false,6autoSave: true,7decorationTimeout: 10000,8document: false,9jdbcDrivers: ['com.mysql.cj.jdbc.Driver','oracle.jdbc.driver.OracleDriver','org.postgresql.Driver','com.microsoft.sqlserver.jdbc.SQLServerDriver','dm.jdbc.driver.DmDriver','org.apache.hive.jdbc.HiveDriver','com.taosdata.jdbc.rs.RestfulDriver'],10datasourceTypes: ['com.zaxxer.hikari.HikariDataSource', 'com.alibaba.druid.pool.DruidDataSource','org.apache.tomcat.jdbc.pool.DataSource','org.apache.commons.dbcp2.BasicDataSource']11// 其它配置参考本页中其它配置项12}
本系统是在原开源magic-api接口快速开发框架的基础上,保留其强大、易用的特性,针对企业权限管控需求及实际项目需要,增加系统用户管理、角色管理、菜单管理、安全性管理、日志管理等功能,整合形成Magic-API接口管理系统。
magic-api接口快速开发框架的特点:
基于Java的接口快速开发框架,编写接口将通过magic-api提供的UI界面完成,自动映射为HTTP接口,无需定义Controller、Service、Dao、Mapper、XML、VO等Java对象即可完成常见的HTTP API接口开发
magic-api官网快速入门、基础教程链接:
本系统通过“用户<->角色<->菜单<->接口”实现用户接口权限管控;用户通过前端UI界面在magic-api平台创建的分组、接口,由系统自动同步到菜单项目中;角色授权时通过勾选对应接口,再分配角色至用户,即可实现对用户前端界面操作接口的权限控制:
一个用户可分配多个角色,权限取各角色权限的并集;
用户自己在magic-api创建成功的分组、接口,无需由管理员额外授权,可由本人即时获得对该分组/接口查看/编辑管理的权限;
分配了“[内置]Magic接口同目录查看”角色的用户,如果拥有某个目录的访问权限,则自动获得其他用户在此目录下创建的接口查看权限(注意不能自动获得此目录下子目录的查看权限);
此模式基于Oauth2.0的客户端凭据机制;这种场景下的授权,便是客户端凭据许可,第三方软件可以直接使用注册时的 client_id 和 client_secret 来换回访问令牌 token 的值。其原理如下:
本系统通过“Client<->角色<->菜单<->接口”实现Client ID接口权限控制;在角色定义界面绑定角色与菜单项目(即接口)的关系 ,再分配角色至指定的Client ID,即可实现对Client ID访问接口的权限控制:
和一个用户可分配多个角色不同,一个Client ID只允许分配一个角色,且Client ID账户无法登录前端系统;
客户端凭据访问接口步骤:
获取动态token(以账号dms-client为例):
| Key | value |
|---|---|
| client_id | dms-client |
| client_secret | 668f73c4-ec2e-8745-0c91-1194133e958b |
| grant_type | client_credentials |
接口访问信息:
| 参数名 | 参数值 | |
|---|---|---|
| 接口地址 | http://127.0.0.1:8888/oauth2/client_token | |
| 调用方式 | POST | |
| 调用参数 | client_id:dms-client client_secret:668f73c4-ec2e-8745-0c91-1194133e958b grant_type:client_credentials | |
| encType | application/x-www-form-urlencoded |
调用接口成功后,返回结果data.client_token值即为获得的动态token;
调用接口:
调用接口时,在Headers中添加access_token参数(POST和GET方式相同),这里的参数值即为上一步获得的动态token:
| 参数名 | 参数值 |
|---|---|
| access_token | mPx6cs5SVPwLznivShOfhSNvjMqcjRYmhDq4irxqKejxW3JNHrwSYNDcEDnl |
匿名模式
对于处在企业内部网络的系统接口调用,采用客户端凭据获取动态token方式比较麻烦,系统提供简化的接口访问方式,跳过身份认证这个步骤:
针对单个接口,在接口配置选项处设置允许匿名访问(anonymous=true):
静态token
相对于匿名模式,需要调用方提供一个固定值的token访问接口;配置步骤:
设置全局静态token(路径:系统管理->参数设置,参数键名:sys.magic.statictoken,参数名称:magic:接口是否启用静态token):
在接口选项处,设置两个选项(enabled_static_token和anonymous为true):
调用接口时,在接口url或header处传入参数token=xxxxxxxxxx(第1步设置的全局静态token值):
通过前端界面,对接口的新增、修改、删除等操作,可通过[接口管理->接口日志->接口操作]查询:
通过接口调用(magic-api管理界面在线调试,或第三方系统调用),对接口的调度操作,可通过[接口管理->接口日志->接口调度]查询:
本系统提供定时任务管理,可实现对接口的调度运行,[系统监控->定时任务]:
配置定时任务调用Magic-API接口时,调用目标字符串各参数的含义:
| 参数项 | 参数说明 | 说明 |
|---|---|---|
| Bean调用名称 | magicTask.run | 固定值 |
| 第一个参数 | 接口调用方式 | 接口的调用方式,get/post |
| 第二个参数 | 接口相对路径 | 这里填写接口的相对路径,如interface/test/queryInfo; 相对路径的获取方式:在Magic-API接口管理界面,鼠标选择接口,右键->复制相对路径 |
| 第三个参数 | 接口参数 | 要传入接口的参数; POST调用 :{body:map},body为固定变量名,map为接口要处理的实际Json参数; GET调用:{paraname1:paravalue1, paraname2:paravalue2,…} |
| 第四个参数 | 接口日志记录 | 是否在[接口管理->接口日志->接口调度]记录接口调度日志信息; true:记录接口调度日志; false:不记录接口调度日志; 注意:不管参数如何设置,在定时任务管理界面的日志按钮查看页面,都可查看接口的调度日志信息; |
执行策略详解:
立即执行:(所有misfire的任务会马上执行)打个比方,如果9,10点的任务都misfire了,在10:15系统恢复之后,9点,10点的misfire会马上执行执行一次:(会合并部分的misfire,正常执行下一个周期的任务)假设9,10点的任务都misfire了,系统在10:15分起来了。只会执行一次misfire,下次正点执行。放弃执行:(所有的misfire不管,执行下一个周期的任务)
系统中内置了接口选项,以下是对各选项作用的说明:
| 选项Key | 选项Value | 选项描述 | 说明 |
|---|---|---|---|
| log | true/false/dbtrace | 是否记录日志(true或留空:记录;false:不记录;dbtrace:记录日志及报文内容) | 未配置或log=true,系统记录接口运行日志;日志信息同时存放在/logs/目录下的info/warn/debug/error子目录的log文件中,以及log数据表中; log=false,系统不记录接口运行日志,针对频繁调用的基础数据接口,如果要避免接口调度过程中大量的日志数据产生,可通过log=false设置来屏蔽; log=dbtrace,系统记录日志结果时,不仅包含log=true参数时的log文件和log数据表,还会将报文参数和返回结果记录在log数据明细表中,此选项会造成数据表空间较快的增长,故建议只在特殊场景需要调试接口时快速追踪日志信息时设置,调试完毕需要关闭切换回log=true; |
| ip | 允许调用本接口的远程机器IP白名单 | IP白名单(多个逗号分隔,支持-和/组合) | 比如在特定场景下,本接口只允许定时任务调度,不允许其它远端系统调用,可设置ip=127.0.0.1; 示例: 192.168.1.1;192.168.3.17-192.168.3.38;192.168.4.0/24 |
| online | true/false | 空或true:接口在线;false:接口下线,只允许UI端调用 | 未配置或online=true,接口允许前端界面调用和第三方系统远程调用; online=false,接口只允许前端界面调用,不允许第三方系统远程调用; |
| enabled_static_token | true/false | 接口是否启用静态token | 未配置或enabled_static_token=true,访问接口时需要提供静态token参数; enabled_static_token=false,接口不启用静态token参数; 注意:接口要启用静态token,需要同时满足两个条件: 1.接口选项enabled_static_token=true; 2.系统参数sys.magic.statictoken指定非none值(静态token值); 一般来说,启用了静态token,就不需要同时启用动态token验证,此时在接口选项中,指定anonymous=true即可; |
| xml_param_in | true/false | 接口参数为xml格式 | 未配置或xml_param_in=false,接口默认json格式报文; xml_param_in=true,接口接受xml格式报文; 系统的处理逻辑:当指定xml_param_in=true,传入xml格式报文后,系统自动将xml报文转换为json格式的报文,此时在接口脚本中,用body接收到的即为json格式的报文; 注意此选项指定为true后,无法直接在前端界面调试,需要通过PostMAN等工具进行调用调试; |
| xml_resp_out | true/false | 返回报文json自动转换为xml格式 | 如果需要接口返回xml格式报文结果,配置xml_resp_out=true,系统自动将接口生成的json报文转换为xml报文,返回给调用方; |
| anonymous | true/false | 该接口不需要登录也可访问 | 未配置或anonymous=false,接口按照正常的客户端凭据访问权限控制; anonymous=true,接口允许匿名访问,在第三方调用时无需提供动态token; 注意:前端调试接口时,不受此参数控制,也无需提供动态token; |
系统内置了参数设置,以下是对各主要参数作用的说明:
| 参数键名 | 参数名称 | 参数值 | 参数说明 |
|---|---|---|---|
| sys.magic.log.maxdays | magic:接口日志最大保留天数 | 30 | 系统保留接口日志的最大天数;超过此数字的接口日志将被定期清除;目前系统设置为每天5:00运行清除任务;清除的日志包括存放在服务器路径上的log文件,以及存放在数据库表中的log日志数据; magic-api接口日志最大保留天数;如果参数值小于7,则系统保留7天; |
| sys.clientid.tokentimeout | magic:ClientId管理-默认超时时间 | 480000 | ClientId通过客户端凭据获取动态token,token默认的超时时间(单位:秒) |
| sys.magic.statictoken | magic:接口是否启用静态token | NONE | NONE:不启用静态token;其它值:启用静态token 此选项和接口选项enabled_static_token配合使用; |
| sys.magic.secure.ip | magic:接口是否启用IP白名单 | *或ip | *:允许任意IP访问;0:禁止所有IP访问; 其它值(多个用;号分隔):192.168.1.1;192.168.3.17-192.168.3.38;192.168.4.0/24 注意:此参数和接口选项ip作用不一样,此参数影响所有接口的访问,接口选项ip只影响特定接口的访问; |
| sys.magic.apientity.sync.status | magic:api entity同步状态 | true/false | false:未同步; true:已同步 此参数设置为false,系统会定时(每隔2分钟扫描一次)将接口的信息完整同步到系统菜单项目中;同步后会将此标识置为true; 后续的接口变化情况(新增、更名、删除),系统会实时同步;故一般情况下,此选项只在系统初始化时设置一次为false即可;如果有特殊情况,比如后台删除了菜单项的相关数据,可以将此参数设置为false,系统重新同步。 |
在定义配置文件application-prod.yml时,涉及到数据库连接密码或远程推送时秘钥等敏感数据:
可以通过加密的方式防止这些敏感数据泄露,具体操作步骤:
确定加密密钥,这里示例如:Magic123,记住这个密钥,后面在生成加密密文以及启用系统时需要;
菜单:系统工具->加密解密,打开加密解密页面:
在Jasypt加密处,密钥处输入第1步确定的加密密钥的Magic123,明文输入root,这个root是配置文件中cfg-datasource.password的密码明文,点击“加密”按钮,生成密文wUO0iddnIn49HTYhbprxLg==;
注意:相同密钥和明文,生成的密文不是唯一的,每点击一次加密,生成的密文都会变化,这里取任意一次生成的密文都可以。
将生成的密文用如下格式替换原来的root密码:ENC(密文)
保存配置文件,用./madmin.sh stop退出系统;用如下命令启动系统:
xxxxxxxxxx11./madmin.sh runsecure
系统提示输入密码:
这里输入第1步确定的加密密钥Magic123,该密钥也是对密码加密后密文的解密密钥。确认系统启动:
magic-api接口平台支持多数据源,包括但不限于(只要符合jdbc规范的都可以)以下数据库,如:
MySQL、MariaDB、Oracle、DB2、PostgreSQL、SQLServer、MongoDB
其它如国产的达梦数据库、涛思数据库等也支持;
本系统内置了MySQL、Oracle、PostgreSQL、SQLServer、MongoDB数据库的驱动,开箱即用。其它数据库需要根据不同版本集成对应jdbc驱动文件才可使用。
本系统对magic-api做了扩展,可支持基础数据类型参数的存储过程调用:
| 参数类型 | 传参方式 | 示例 |
|---|---|---|
| IN | @{参数名(参数值), 字段类型} | @{p_batch_id(p_batch_id),VARCHAR} |
| OUT | @{参数名,字段类型} | @{x_return_code, VARCHAR} |
| IN OUT | @{参数名(参数值), 字段类型} | @{x_return_msg(x_message),VARCHAR} |
本系统对接口调用做了扩展,支持调用时XML报文参数;注意这不是基于XML的WebService服务,只是支持XML数据的HTTP调用;
要启用接口对XML报文作为传入参数的支持,在接口配置选项处指定xml_param_in=true:
传入XML参数时,前端界面无法直接调试,可通过PostMAN等工具进行测试;
要启用接口对XML报文作为传出结果的支持,在接口配置选项处指定xml_resp_out=true:
设置前的输出结果:
设置后的输出结果: